Eeprom interface #355

medamawa · 2026-01-03T00:20:10Z

Changes

Completely refactored the EEPROM directory architecture from a partition-based system to a key-value storage system with dynamic block allocation. The new implementation provides a more flexible and efficient way to store and retrieve data in EEPROM.

Notes

Public API: The public API is only in middleware/inc/eeprom_directory.h. All other header files (eeprom_alloc.h, eeprom_storage.h, eeprom_directory_struct.h) are internal implementation details and should not be used directly by application code.
The old partition-based API is completely replaced. Old code using eeprom_get_base_address() etc. will need to be migrated.
Maximum value size is 16 bytes (4 blocks × 4 bytes per block)
Keys are fixed 4-byte arrays, not null-terminated strings
The allocation table and key map are persisted in EEPROM
Memory layout: Allocation table (64 bytes) → Key map (1536 bytes) → Data space (2048 bytes)

Test Cases

Single byte value storage and retrieval
Multi-block value storage (up to 16 bytes)
Key overwrite behavior
Value deletion and block reuse
Error handling (null pointers, not found, allocation failures)
Allocation table state verification

To Do

Optimize memory allocation
Add unit tests
...

Checklist

It can be helpful to check the Checks and Files changed tabs.
Please reach out to your Project Lead if anything is unclear.
Please request reviewers and ping on slack only after you've gone through this whole checklist.

No merge conflicts
All checks passing
Remove any non-applicable sections of this template
Assign the PR to yourself
Request reviewers & ping on Slack
PR is linked to the ticket (fill in the closes line below)

Closes # (issue #329 )

…ectric-Racing/Embedded-Base into eeprom_interface

medamawa · 2026-01-18T21:12:06Z

EEPROM Directory API Usage Guide

Overview

The EEPROM Directory API provides a simple interface for managing a key-value directory stored on an EEPROM device. This API allows you to persistently store, retrieve, and delete values associated with fixed-size (4-byte) keys, with values up to 16 bytes in size.

Key Features

Key-Value Storage: Store 4-byte keys with values up to 16 bytes
Persistence: Data is stored on EEPROM and persists across power cycles
Block-Based Management: Data is managed in 4-byte blocks
Automatic Memory Management: Block allocation and deallocation are handled automatically

Inputs and Outputs

Inputs

Key: A fixed-size 4-byte key (not a null-terminated string)
- Example: "tsms", "dcnt", "name"
Value: Data up to 16 bytes (4 blocks) in size
- Example: 21, "sogo"
M24C32 Device: Pointer to the EEPROM device interface
- m24c32_t

Outputs

Status Code: Error code of type eeprom_status_t
- EEPROM_OK: Success
- EEPROM_ERROR_NOT_FOUND: Key not found
- EEPROM_ERROR_ALLOCATION: Memory allocation failed
- EEPROM_ERROR_TOO_BIG: Data size exceeds 16 bytes
- Other error codes (see eeprom_status.h)
Retrieved Data: For get_directory_value() function, a pointer to a dynamically allocated buffer (caller must free)

API Functions

1. `directory_init()` - Initialize Directory

Initializes the directory structure and loads the allocation table and key map from EEPROM.

Function Signature:

eeprom_status_t directory_init(m24c32_t *device, eeprom_directory_t *directory);

Parameters:

device: Pointer to the M24C32 device interface
directory: Pointer to the directory structure to initialize (must be allocated by caller)

Return Values:

EEPROM_OK: Initialization successful
EEPROM_ERROR_NULL_POINTER: Parameter is NULL
EEPROM_ERROR: Initialization failed

2. `set_directory_value()` - Store Value

Stores data with the specified key. If the key already exists, the old value is deleted first before storing the new value.

Function Signature:

eeprom_status_t set_directory_value(eeprom_directory_t *directory,
                                    const uint8_t *key, 
                                    uint8_t *value,
                                    const uint16_t value_size);

Parameters:

directory: Pointer to the initialized directory structure
key: Pointer to a 4-byte key
value: Pointer to the data to store
value_size: Size of the data in bytes (maximum 16 bytes)

Return Values:

EEPROM_OK: Store successful
EEPROM_ERROR_NULL_POINTER: Parameter is NULL
EEPROM_ERROR_TOO_BIG: Data size exceeds 16 bytes
EEPROM_ERROR_ALLOCATION: Block allocation failed

3. `get_directory_value()` - Retrieve Value

Retrieves data associated with a key. The output buffer is dynamically allocated by this function and must be freed by the caller.

Function Signature:

eeprom_status_t get_directory_value(eeprom_directory_t *directory,
                                    const uint8_t *key, 
                                    uint8_t **out,
                                    uint16_t *out_size);

Parameters:

directory: Pointer to the initialized directory structure
key: Pointer to a 4-byte key
out: Pointer to a pointer that will receive the allocated output buffer
out_size: Pointer to store the size of the output data in bytes

Return Values:

EEPROM_OK: Retrieve successful
EEPROM_ERROR_NULL_POINTER: Parameter is NULL
EEPROM_ERROR_NOT_FOUND: Key does not exist
EEPROM_ERROR_ALLOCATION: Memory allocation failed

Note: The retrieved buffer must be freed using free().

4. `delete_directory_value()` - Delete Value

Deletes a key and its associated data, freeing the related blocks.

Function Signature:

eeprom_status_t delete_directory_value(eeprom_directory_t *directory,
                                       const uint8_t *key);

Parameters:

directory: Pointer to the initialized directory structure
key: Pointer to a 4-byte key

Return Values:

EEPROM_OK: Delete successful
EEPROM_ERROR_NULL_POINTER: Parameter is NULL
EEPROM_ERROR_NOT_FOUND: Key does not exist

Usage Example: Car Fault Directory

The following examples demonstrate how to store and retrieve car fault information using the EEPROM directory.

Example 1: Initialize Directory and Write Fault Information

#include "eeprom_directory.h"
#include "m24c32.h"

// Fault code definitions (4-byte keys)
#define FAULT_KEY_ENGINE_TEMP    {0x01, 0x00, 0x00, 0x01}  // Engine temperature fault
#define FAULT_KEY_BRAKE_PRESSURE {0x01, 0x00, 0x00, 0x02}  // Brake pressure fault
#define FAULT_KEY_BATTERY_VOLT   {0x01, 0x00, 0x00, 0x03}  // Battery voltage fault

// Fault record structure (maximum 16 bytes)
typedef struct {
    uint32_t timestamp;      // Fault occurrence time (4 bytes)
    uint16_t fault_code;      // Fault code (2 bytes)
    uint8_t  severity;        // Severity (1 byte: 0=minor, 1=warning, 2=critical)
    uint8_t  reserved[9];     // Reserved area (9 bytes)
} fault_record_t;

void example_car_fault_storage(void) {
    m24c32_t eeprom_device;
    eeprom_directory_t directory;
    eeprom_status_t status;
    
    // 1. Initialize EEPROM device (implementation is project-dependent)
    // m24c32_init(&eeprom_device, ...);
    
    // 2. Initialize directory
    status = directory_init(&eeprom_device, &directory);
    if (status != EEPROM_OK) {
        // Error handling
        return;
    }
    
    // 3. Store engine temperature fault information
    uint8_t engine_temp_key[4] = FAULT_KEY_ENGINE_TEMP;
    fault_record_t engine_fault = {
        .timestamp = 1234567890,  // Example: Unix timestamp
        .fault_code = 0x1001,
        .severity = 2,            // Critical
        .reserved = {0}
    };
    
    status = set_directory_value(&directory, 
                                 engine_temp_key,
                                 (uint8_t *)&engine_fault,
                                 sizeof(fault_record_t));
    if (status != EEPROM_OK) {
        // Error handling
        return;
    }
    
    // 4. Store brake pressure fault information
    uint8_t brake_key[4] = FAULT_KEY_BRAKE_PRESSURE;
    fault_record_t brake_fault = {
        .timestamp = 1234567891,
        .fault_code = 0x2001,
        .severity = 1,            // Warning
        .reserved = {0}
    };
    
    status = set_directory_value(&directory,
                                 brake_key,
                                 (uint8_t *)&brake_fault,
                                 sizeof(fault_record_t));
    if (status != EEPROM_OK) {
        // Error handling
        return;
    }
    
    // 5. Store battery voltage fault information
    uint8_t battery_key[4] = FAULT_KEY_BATTERY_VOLT;
    fault_record_t battery_fault = {
        .timestamp = 1234567892,
        .fault_code = 0x3001,
        .severity = 0,            // Minor
        .reserved = {0}
    };
    
    status = set_directory_value(&directory,
                                 battery_key,
                                 (uint8_t *)&battery_fault,
                                 sizeof(fault_record_t));
    if (status != EEPROM_OK) {
        // Error handling
        return;
    }
}

Example 2: Read Fault Information

void example_read_car_faults(void) {
    m24c32_t eeprom_device;
    eeprom_directory_t directory;
    eeprom_status_t status;
    
    // Initialize directory (same as previous example)
    status = directory_init(&eeprom_device, &directory);
    if (status != EEPROM_OK) {
        return;
    }
    
    // Retrieve engine temperature fault information
    uint8_t engine_temp_key[4] = FAULT_KEY_ENGINE_TEMP;
    uint8_t *fault_data = NULL;
    uint16_t fault_data_size = 0;
    
    status = get_directory_value(&directory,
                                 engine_temp_key,
                                 &fault_data,
                                 &fault_data_size);
    
    if (status == EEPROM_OK) {
        // Successfully retrieved data
        fault_record_t *fault = (fault_record_t *)fault_data;
        
        printf("Fault code: 0x%04X\n", fault->fault_code);
        printf("Timestamp: %lu\n", (unsigned long)fault->timestamp);
        printf("Severity: %d\n", fault->severity);
        
        // Free memory (important!)
        free(fault_data);
        fault_data = NULL;
    } else if (status == EEPROM_ERROR_NOT_FOUND) {
        printf("Fault information not found\n");
    } else {
        printf("Error occurred: %d\n", status);
    }
}

Example 3: Update and Delete Fault Information

void example_update_and_delete_fault(void) {
    m24c32_t eeprom_device;
    eeprom_directory_t directory;
    eeprom_status_t status;
    
    // Initialize directory
    status = directory_init(&eeprom_device, &directory);
    if (status != EEPROM_OK) {
        return;
    }
    
    uint8_t engine_temp_key[4] = FAULT_KEY_ENGINE_TEMP;
    
    // Update existing fault information (set_directory_value automatically deletes old value)
    fault_record_t updated_fault = {
        .timestamp = 1234568000,  // New timestamp
        .fault_code = 0x1002,     // Updated fault code
        .severity = 1,             // Updated severity
        .reserved = {0}
    };
    
    status = set_directory_value(&directory,
                                 engine_temp_key,
                                 (uint8_t *)&updated_fault,
                                 sizeof(fault_record_t));
    if (status != EEPROM_OK) {
        // Error handling
        return;
    }
    
    // Delete fault information (e.g., when issue is resolved)
    status = delete_directory_value(&directory, engine_temp_key);
    if (status == EEPROM_OK) {
        printf("Fault information deleted\n");
    } else if (status == EEPROM_ERROR_NOT_FOUND) {
        printf("Fault information to delete not found\n");
    }
}

Important Notes

Memory Management: Buffers retrieved from get_directory_value() must be freed using free().
Key Format: Keys are fixed-size 4-byte values, not null-terminated strings. If using strings, pad to 4 bytes or use a hash value.
Data Size Limit: Maximum 16 bytes (4 blocks) of data can be stored per key.
Key Count Limit: Maximum 128 key-value pairs can be stored (KEY_MAP_COUNT).
Block Size: Data is managed in 4-byte blocks. If data size is not a multiple of 4 bytes, remaining bytes are padded with zeros.
Error Handling: Always check return values from all function calls and handle errors appropriately.
Initialization Requirement: Always call directory_init() before using the directory.

Related Files

eeprom_directory.h: Main API header file
eeprom_directory_struct.h: Data structure and constant definitions
eeprom_status.h: Error code definitions
eeprom_alloc.h: Block allocation management
eeprom_storage.h: Data storage management

medamawa · 2026-01-18T21:14:47Z

This repository includes the same code for this API, as well as additional test code (though it's a bit messy).
https://github.com/medamawa/eeprom_mock

medamawa and others added 9 commits December 15, 2025 18:50

fix the comment at the top of eeprom_directory.h

8772f98

re-implement eeprom directory

d154fa3

refactor for clang-format

51c4efd

Merge branch 'main' into eeprom_interface

a94c4ef

additional code formatting

8e52deb

Merge branch 'eeprom_interface' of https://github.com/Northeastern-El…

05393a1

…ectric-Racing/Embedded-Base into eeprom_interface

additional code formatting

e40ada3

formatting

861d6c3

format by clang-format

78ddf1c

medamawa self-assigned this Jan 20, 2026

medamawa requested a review from caiodasilva2005 January 20, 2026 02:00

medamawa added 4 commits January 19, 2026 22:01

add underscores before all private functions

7c2a1dd

clang-formatting

cd47ac2

clang-formatting

501c3c4

use device->read/write instead of using m24c32_read/write directory

de87088

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Eeprom interface #355

Eeprom interface #355

Uh oh!

medamawa commented Jan 3, 2026 •

edited

Loading

Uh oh!

medamawa commented Jan 18, 2026

Uh oh!

medamawa commented Jan 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Eeprom interface #355

Are you sure you want to change the base?

Eeprom interface #355

Uh oh!

Conversation

medamawa commented Jan 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Notes

Test Cases

To Do

Checklist

Uh oh!

medamawa commented Jan 18, 2026

EEPROM Directory API Usage Guide

Overview

Key Features

Inputs and Outputs

Inputs

Outputs

API Functions

1. directory_init() - Initialize Directory

2. set_directory_value() - Store Value

3. get_directory_value() - Retrieve Value

4. delete_directory_value() - Delete Value

Usage Example: Car Fault Directory

Example 1: Initialize Directory and Write Fault Information

Example 2: Read Fault Information

Example 3: Update and Delete Fault Information

Important Notes

Related Files

Uh oh!

medamawa commented Jan 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

medamawa commented Jan 3, 2026 •

edited

Loading

1. `directory_init()` - Initialize Directory

2. `set_directory_value()` - Store Value

3. `get_directory_value()` - Retrieve Value

4. `delete_directory_value()` - Delete Value